home *** CD-ROM | disk | FTP | other *** search
/ Turnbull China Bikeride / Turnbull China Bikeride - Disc 2.iso / STUTTGART / UTIL / SCREEN / WPAPER / Help < prev    next >
Text File  |  1993-09-13  |  5KB  |  178 lines
  1. Introduction
  2. ~~~~~~~~~~~~
  3.  
  4. WallPaper is a utility that allows you to have a randomly
  5. selected sprite as your backdrop. The backdrop can also
  6. be updated at regular intervals if you wish. It only works 
  7. under RISC OS 3, and is only useful on a hard disc machine.
  8.  
  9. **********************************************************
  10.  
  11. Before you Start
  12. ~~~~~~~~~~~~~~~
  13.  
  14. Before WallPaper is run, two system variables must be
  15. defined:
  16.  
  17. 1) BackDrop$Path is the path on which the sprites to use are
  18. found. Thus if you have a collection of sprites in, say, the
  19. directory
  20.  
  21. adfs::HD4.$.Resources.Backdrops
  22.  
  23. You should issue the command
  24.  
  25. Set Backdrop$Path adfs::HD4.$.Resources.Backdrops.
  26.  
  27. Note carefully the final '.' on this line. 
  28.  
  29. (Shift-Drag of a file into a text editor generally inserts
  30. the full file specification at the cursor, which may be
  31. useful)
  32.  
  33. 2)  Wallpaper actually uses the command 'BDrop' to load
  34. a backdrop. This does nothing! Seriously, you should create
  35. an alias for BDrop that load your backdrops in the way you
  36. want. A suitable command is
  37.  
  38. SetMacro Alias$BDrop Backdrop -C Backdrop:<BackDrop$Current>
  39.  
  40. You can alter the -C to -S or -T if you want your sprites
  41. scaled or tiled instead of centred. This must be a macro.
  42.  
  43. **********************************************************
  44.  
  45. Usage
  46. ~~~~~
  47.  
  48. Now you can run WallPaper. This does nothing immediately.
  49.  
  50. You will find now, however, that 
  51.  
  52. Set BackDrop$Interval n
  53.  
  54. will cause a fresh, randomly selected, sprite to be loaded
  55. every <n> seconds. Do not make <n> too small! I would say 
  56. that 20 seconds is about the most frequently that any sane
  57. person could stand a change of backdrop.
  58.  
  59. An important exception is an <n> of zero (and any non-number
  60. will evaluate as zero)
  61.  
  62. Set BackDrop$Interval 0
  63.  
  64. which will load a backdrop immediately, but does not repeat.
  65.  
  66. **********************************************************
  67.  
  68. In !Boot Files
  69. ~~~~~~~~~~~~~~
  70.  
  71. The best way to use WallPaper is in a !Boot 
  72. file/application.
  73.  
  74. (Part of) my !Boot application does:-
  75.  
  76. Set BackDrop$Path Boot:!Backdrops.Backdrops.
  77. SetMacro Alias$BDrop Backdrop -C Backdrop:<Backdrop$Current>
  78. WallPaper
  79. Set BackDrop$Interval 0
  80. Set BackDrop$Interval 60
  81.  
  82. Notice the Set 0 .. Set 60 This gives me a backdrop 
  83. immediately and then changes it every sixty seconds.
  84.  
  85.  
  86. **********************************************************
  87.  
  88. Extensions
  89. ~~~~~~~~~~
  90.  
  91. The advantage of using the 'BDrop' alias and having 
  92. 'BackDrop$Path' is that you can set up application folders
  93. containing backdrop sprites, and with !Run files similar
  94. to
  95.  
  96. Set Backdrop$Path <Obey$Dir>.
  97. Set BDrop -<whichever> Backdrop:<Backdrop$Current>
  98. Set Backdrop$Interval <n>
  99.  
  100. so you can have lots of backdrops, centre-able "?" ones in 
  101. one directory, scaleable in another, tile-able in a third.
  102.  
  103. You should ideally set Backdrop$Interval whenever the
  104. number of files in the directory changes to ensure that 
  105. the code notices the new files (or missing ones). 
  106.  
  107. Deleting sprites from the current backdrop directory is ok.
  108. Adding them is also ok, but you should then do a set 
  109. Backdrop$Interval so that the changes are noticed.
  110.  
  111.  
  112. **********************************************************
  113.  
  114. Technical Details
  115. ~~~~~~~~~~~~~~~~~
  116.  
  117. If you've got this far, you'll have guessed by now that
  118. WallPaper is implemented as a code variable.
  119.  
  120. Running WallPaper sets up BackDrop$Interval as a code
  121. variable.
  122.  
  123. Reading BackDrop$Interval returns an integer value. 
  124.  
  125. Writing to it with a non-zero value, call this V, (as
  126. evaluated by OS_ReadUnsigned) causes, more-or-less, the
  127. following:
  128.  
  129. i)   Immediately, the number of files in the first directory
  130.      on the path Backdrop: is evaluated. Call this N.
  131.  
  132. ii)  After at least V seconds code is executed which 
  133.      selects a random integer in the range 1..N. The name
  134.      of the 0th..(N-1)th file in the backdrop directory is
  135.      resolved, checked for beiing of sprite file type and
  136.      stored it in another variable Backdrop$Current.
  137.  
  138. iii) Finally the command 'BDrop' is issued (which can
  139.      be aliased to anything at all, but is intended to
  140.      be 'BackDrop Backdrop:<Backdrop$Current>'.
  141.     
  142. Note that the only way of removing a code variable
  143. is to use OS_SetVarVal with the right parameters. It's
  144. considered a very good idea to do a 
  145.  
  146. Set BackDrop$Interval 0 
  147.  
  148. to make it quiescent first, however. Calling non-existent
  149. code from an interrupt is harmful to your machine's health.
  150.  
  151. Errors:
  152.  
  153. If WallPaper spots anything wrong it calls OS_GenerateError
  154. which will generally produce a useful error message.
  155.  
  156. Loading the backdrop may also produce error messages, a 
  157. quite frequent one (on my machine) is 'insufficent memory
  158. to load backdrop sprite'. Serves me right.
  159.  
  160. One thing that WallPaper does handle internally is trying
  161. to load non-sprite files. If the 'new' file isn't a sprite
  162. it leaves BackDrop$Current unaltered - i.e. the previous
  163. backdrop will be reloaded. A waste of time. So, while
  164. one or two non-sprite files in a 'backdrops' directory,
  165. e.g. subdirectories, are harmless enough, you should avoid
  166. pointing BackDrop$Path at directories that contain the
  167. inverse mix - a few sprites and lots of other files. 
  168.  
  169. I have chosen not to distribute source code to save
  170. bandwidth. If anyone wants it mail me as 
  171. aoliver@acorn.co.uk
  172.  
  173. Ashley Oliver
  174. Sep 10th, 1993
  175.  
  176.  
  177. **********************************************************
  178.